#AI 智能体功能指南

模型编排（AI Flow）是 PIGX AI 平台提供的可视化工作流设计工具，支持通过拖拽节点的方式构建复杂的 AI 应用流程。

#系统架构

flowchart LR
  A[其他系统] -->|HTTP API| B[PIG AI FLOW]
  A -->|Java SDK| B
  B --> C[DeepSeek]
  B --> D[Qwen]
  B --> E[其他AI模型]

外部系统可以通过 HTTP API 或 Java SDK 两种方式调用已编排的 AI Flow，平台会根据配置调用相应的 AI 模型（如 DeepSeek、Qwen 等）完成任务。

#调用方式区别

AI Flow 支持两种调用模式,系统会根据节点类型和配置自动选择合适的调用方式:

#流式调用(Stream)

特点:

• 大模型实时返回内容,用户可见逐字输出效果
• 节点执行完毕后,后续节点的逻辑不会输出给前端用户
• 适合需要实时反馈的交互场景

使用建议:

• 如需流式输出,建议将支持流式的节点(如 LLM、RAG)放在整个流程的最后
• 这样用户可以看到完整的流式生成过程

示例流程:

flowchart LR
  A[开始节点] --> B[数据处理]
  B --> C[LLM节点<br/>流式]
  C --> D[结束节点]
  C -.实时输出.-> E((用户))

#非流式调用(Non-Stream)

特点:

• 大模型走完整个流程后输出最终结果
• 所有节点执行完成后才返回给前端
• 适合需要完整处理结果的场景

使用建议:

• 适合复杂的多步骤处理流程
• 当需要对大模型输出做进一步处理时使用

示例流程:

flowchart LR
  A[开始节点] --> B[LLM节点<br/>非流式]
  B --> C[结构化输出]
  C --> D[数据存储]
  D --> E[结束节点]
  E -.返回.-> F((最终结果))

#支持流式的节点列表

以下节点支持流式和非流式两种调用模式:

错误示例（流式节点后接流式节点）:

flowchart LR
  A[开始节点] --> B[LLM节点<br/>流式]
  B --> C[RAG节点<br/>流式]
  C --> D[结束节点]
  B -.SSE连接.-> E((用户))
  C -.❌ 连接已断开.-> E
  style C fill:#ffcccc

在上述错误示例中,LLM 节点执行完毕后 SSE 连接断开,RAG 节点的流式输出无法送达用户。

#节点分类

系统提供 22 种节点类型，分为 5 大类别：

• 流程控制（4个节点）：开始、结束、分支、循环
• AI能力（7个节点）：LLM大模型、问题分类、结构化输出、RAG知识库、MCP服务、OCR识别、文档解析
• 多模态（2个节点）：图片生成、音频生成
• 数据处理（3个节点）：执行代码、文本节点、DB数据库
• 外部集成（4个节点）：HTTP请求、消息通知、Dify工作流、Coze对话

#变量占位符说明

系统会在运行时自动将占位符替换为实际的变量值，实现节点间的数据传递。

#流程控制节点

#开始节点（Start）

工作流的起始节点，每个工作流必须有且仅有一个开始节点。用于定义工作流的输入参数，作为后续节点的数据源。

配置项

变量列表

定义工作流的输入参数，支持以下组件类型：

输出变量

• result（Object）：开始节点接收到的全部输入参数

#结束节点（End）

工作流的结束节点，标记流程执行完毕。

输出变量

• content（Object）：结束节点接收到的最终输出对象
• result（Object）：流程最终结果对象

#分支节点（Switch）

根据条件判断选择不同的执行分支，支持多路分支。

配置项

变量输入

• 添加输入变量，从前序节点选择输出变量

分支判断代码

• 编写 JavaScript 函数判断逻辑
• 函数签名：function main(args) { return 0; }
• 返回值：分支索引（从0开始）
• 支持占位符：通过 args.arg1 访问输入变量

示例代码：

function main(args) {
  // 根据参数选择分支
  return args.arg1 === "xxx" ? 0 : 1;
}

分支列表

• 分支名称：显示在连线上的标签
• 分支值：对应函数返回值（数字索引）

输出变量

• index（Number）：选中的分支索引
• result（String）：JavaScript 函数 main(args) 的返回值

#循环节点（Loop）

重复执行子流程，支持迭代控制和批量处理。

配置项

最大迭代次数

• 限制循环执行的最大次数（默认10次）

迭代变量名

• 当前迭代索引的变量名（默认 index）
• 子流程中可通过 ${index} 访问当前迭代次数

子流程配置

• 在循环节点内部设计子工作流
• 子流程可访问父流程变量和迭代变量

输出变量

• iterations（Number）：最大迭代次数

#AI能力节点

#LLM大模型（LLM）

调用大语言模型进行对话和文本生成，支持多轮对话和多模态输入。

配置项

变量输入

• 添加输入变量，从前序节点选择输出变量

对话消息

• 角色类型：USER（用户）、SYSTEM（系统）、AI（助手）
• 消息内容：支持占位符 ${变量名}
• 可拖拽调整消息顺序
• 支持多条消息构建上下文

示例提示词：

你是一个专业的文档助手。

用户问题：${arg1}

请提供详细的解答。

模型配置

• 多模态：选择是否使用视觉模型
  • 否：普通文本模型
  • 是：支持图片输入的视觉模型
• 大模型：选择具体模型（根据多模态选项过滤）
• 图片来源（仅多模态）：选择包含图片URL的变量

高级参数

• max_tokens：最大生成令牌数（默认4096）
• temperature：温度参数，控制随机性（0-2，默认0.7）
• top_p：核采样参数（0-1，默认1）
• frequency_penalty：频率惩罚（-2到2，默认0）
• presence_penalty：存在惩罚（-2到2，默认0）
• stream：是否流式输出（默认true）

输出变量

• content（String）：模型生成的文本内容

#问题分类（Question）

使用 AI 对用户问题进行智能分类，根据分类结果选择后续处理分支。

配置项

变量输入

• 添加输入变量（通常是用户问题）

对话消息

• 配置分类提示词，支持占位符 ${变量名}

示例提示词：

你是一个问题分类助手。

任务：根据用户提问 ${arg1}，判断问题类型并返回类别编号。

类别说明：
1. 技术问题
2. 业务咨询
3. 投诉建议

模型配置

• 选择分类使用的大模型
• 建议使用较小的快速模型

分类列表

• 类别名称：分类标签
• 类别值：对应的类别编号

输出变量

• index（Number）：分类命中的分支索引
• result（String）：分类结果值

#结构化输出（Structured）

将 AI 输出转换为结构化 JSON 格式，便于后续节点处理。

配置项

变量输入

• 添加输入变量

对话消息

• 配置提示词，描述需要提取的结构化信息
• 支持占位符 ${变量名}

示例提示词：

从以下文本中提取个人信息：${arg1}

请按照指定的 JSON 格式返回结果。

模型配置

• 选择支持结构化输出的模型

输出字段定义

• 字段名：JSON 字段的键名
• 类型：String、Number、Boolean、Object、Array
• 描述：字段说明（可选）

示例字段定义：

• name (String) - 姓名
• age (Number) - 年龄
• email (String) - 电子邮箱
• skills (Array) - 技能列表

JSON Schema 预览

• 自动生成并显示 JSON Schema

输出变量

• result（Object）：结构化 JSON 对象
• tokens（Number）：本次调用消耗的 Token 数

#RAG知识库（RAG）

检索增强生成，从知识库中检索相关信息并结合大模型生成回答。

配置项

变量输入

• 添加输入变量（通常是用户查询）

知识库选择

• 从已创建的知识库列表中选择

仅召回

• 否：检索后使用大模型生成回答
• 是：仅返回检索到的原始文档片段

提示词

• 配置 RAG 提示词模板
• 支持占位符 ${变量名}

示例提示词：

基于以下检索到的知识库内容，回答用户问题。

用户问题：${arg1}

请提供准确、详细的答案。

输出变量

• result（String / Array）：RAG 生成结果；开启“仅召回”且为非流式调用时返回召回结果数组
• ragSearched（String）：是否命中检索内容，返回 1 或 0

#MCP服务（MCP）

调用模型上下文协议（Model Context Protocol）服务，扩展 AI 能力。

配置项

变量输入

• 添加输入变量

MCP 服务

• 选择已配置的 MCP 服务
• 显示服务名称和类型

请求提示词

• 发送给 MCP 服务的提示内容
• 支持占位符 ${变量名}

示例：

查询天气信息：${arg1}

输出变量

• content（String）：MCP 服务返回的文本内容
• role（String）：固定为 assistant
• tokens（Number）：本次调用消耗的 Token 数

#OCR识别（OCR）

图像文字识别，从图片中提取文本内容。

配置项

变量输入

• 添加输入变量（图片 URL 或 Base64）

OCR 配置选择

• 选择已配置的 OCR 识别配置

高级分析

• 否：仅返回识别的文本
• 是：使用 AI 模型进一步分析识别结果

模型配置（高级分析开启时）

• 对话模型：用于文本分析的模型
• 视觉模型：用于图像理解的多模态模型

输出变量

• result（Object）：OCR 服务返回的原始识别结果对象

#文档解析（DocumentParser）

解析 Office 和 PDF 文档，提取文本内容。

配置项

变量输入

• 添加输入变量（文档 URL 或文件路径）

解析策略

• AUTO：自动检测文档类型
• PDF：强制使用 PDF 解析器
• OFFICE：强制使用 Office 解析器

输出变量

• result（String）：提取的文本内容

#多模态节点

#图片生成（ImageGen）

根据文本描述生成图片，支持文生图和图生图。

配置项

变量输入

• prompt：提示词来源（必选）
• image：参考图片（可选，用于图生图）

生成配置

模型选择

• 选择图像生成模型（类型：Image）

正向提示词

• 描述想要生成的图像内容
• 当未绑定变量时使用此静态值
• 绑定变量时，变量值会替换此处内容

负向提示词

• 描述不希望出现的内容

图像尺寸

• 512x512、768x768、1024x1024
• 1024x768（横向）、768x1024（纵向）

高级参数

• 批次大小：一次生成的图片数量（1-4）
• 随机种子：控制生成结果的随机性（0为随机）
• 推理步数：生成质量，越高越精细（1-100，默认20）
• 引导系数：提示词遵循程度（1-20，默认7.5）

输出变量

• imageUrl（String）：前端可直接渲染的 Markdown 图片内容
• result（String）：图像生成接口返回的原始图片访问路径

#音频生成（VoiceGen）

将文本转换为语音（TTS）。

配置项

变量输入

• input：输入文本来源（必选）

生成配置

TTS模型

• 选择语音合成模型（类型：Voice）

音色选择

• Alex、Anna、Bella、Benjamin、Charles、Claire、David、Diana

语速调节

• 范围：0.5 - 2.0
• 默认：1.0（正常速度）

音量增益

• 范围：-10 到 10 dB
• 默认：0（原始音量）

输出变量

• audioUrl（String）：前端可直接播放的 HTML 音频内容
• result（String）：语音生成接口返回的原始音频访问路径

#数据处理节点

#执行代码（Code）

执行自定义 JavaScript 代码，进行数据转换和处理。

配置项

变量输入

• 添加输入变量，在代码中可通过 args 对象访问

代码编辑

• 编写 JavaScript 函数
• 函数签名：function main(args) { return ""; }
• 可访问输入变量：args.变量名

示例代码：

function main(args) {
  const text = args.arg1;
  return text.toUpperCase();
}

输出变量

• result（String）：代码执行返回值

#文本节点（Text）

输出固定或动态文本内容。

配置项

变量输入

• 添加输入变量（可选）

文本内容

• 输入要返回的文本内容
• 最大长度：5000 字符
• 支持占位符 ${变量名}

示例：

欢迎 ${userName}！

您的订单号是：${orderId}

输出变量

• content（String）：文本内容
• result（String）：文本内容

#DB数据库（DB）

执行数据库 SQL 查询，获取或操作数据。

配置项

变量输入

• 添加输入变量，可在 SQL 中使用

数据源选择

• 从已配置的数据源列表中选择

SQL语句

• 编写 SQL 查询语句
• 支持占位符 ${变量名}

示例 SQL：

SELECT * FROM users
WHERE username = '${arg1}'
LIMIT 10

输出变量

• result（Array）：查询结果行数据数组
• sql（String）：实际执行的 SQL 语句

#外部集成节点

#HTTP请求（HTTP）

发送 HTTP/HTTPS 请求到外部 API，集成第三方服务。

配置项

变量输入

• 添加输入变量，用于构建请求

请求方法

• 方法：GET、POST、PUT、DELETE
• URL：请求地址，支持占位符 ${变量名}

示例：

https://api.example.com/users/${userId}

请求参数（Params 标签页）

• 参数名称：Query 参数的键
• 变量值：选择输入变量或固定值

请求体（Body 标签页）

• 仅 POST、PUT 方法显示
• 内容类型：
  • 无
  • Form Data（application/x-www-form-urlencoded）
  • JSON（application/json）
• Form Data：添加键值对，值支持变量绑定
• JSON：使用 JSON 编辑器，可引用变量

请求头（Headers 标签页）

• Header 名称：如 Authorization
• 变量值：选择输入变量或固定值

输出变量

• body（String）：HTTP 响应体内容
• status（Number）：HTTP 状态码
• headers（Object）：HTTP 响应头
• result（String）：与 body 相同，便于后续节点继续引用

#消息通知（Notice）

发送消息通知到外部系统（如钉钉、企业微信等）。

配置项

变量输入

• 添加输入变量

消息内容

• 编写通知消息文本
• 支持占位符 ${变量名}

示例：

【系统通知】

用户 ${userName} 提交了新的工单。

工单编号：${ticketId}
问题描述：${description}

输出变量

• result（Boolean）：发送是否成功

#Dify工作流（Dify）

调用外部 Dify 平台的 Workflow 能力。

配置项

变量输入

• 添加输入变量

Dify 服务配置

• 服务地址：Dify API 地址（如 https://api.dify.ai）
• API Key：Dify 应用密钥（格式：app-xxxxx）
• 用户标识：用户 ID（可选）
• 超时时间：请求超时设置（10-300秒）
• 输出字段：从 Dify 响应中提取的字段名（默认 text）

Workflow 输入参数

• Dify变量名：Dify Workflow 中定义的变量名
• 变量值：映射的输入变量，使用 ${变量名} 格式

示例映射：

• query → ${arg1}
• context → ${arg2}

文件映射

• Dify变量名：Dify 中的文件输入变量
• 文件URL变量：包含文件 URL 的输入变量
• 类型：文档（document）或图片（image）

输出变量

• content（String）：Dify 返回的主要内容
• result（Object，可选）：阻塞模式下返回的完整 outputs 对象
• workflowRunId（String，可选）：阻塞模式下返回的工作流运行 ID
• taskId（String，可选）：阻塞模式下返回的任务 ID
• tokens（Number，可选）：流式模式下返回的 Token 统计
• timestamp（Number）：节点执行时间戳

#Coze对话（Coze）

调用 Coze 平台的 Bot 进行对话。

配置项

变量输入

• 添加输入变量

Coze 服务配置

• 服务地址：选择服务区域
  • 国内：https://api.coze.cn
  • 国际：https://api.coze.com
• API Key：Coze 个人访问令牌（格式：pat_xxxxxx）
• Bot ID：Coze Bot 的唯一标识
• 用户标识：用户 ID（可选）
• 超时时间：请求超时设置（10-300秒）
• 输出字段：从 Coze 响应中提取的字段名（默认 content）

对话输入参数

• 参数名：传递给 Bot 的参数名
• 变量值：映射的输入变量，使用 ${变量名} 格式

示例映射：

• content → ${arg1}
• user_id → ${userId}

输出变量

• content（String）：Bot 回复内容
• tokens（Number）：消耗的令牌数
• conversationId（String）：对话 ID

#节点连接规则

#变量传递机制

#变量引用格式

1. 当前节点输入变量：${变量名}
2. 指定节点输出变量：${节点ID.变量名}
3. 代码节点特殊访问：args.变量名（JavaScript 对象）

#变量类型

• String：字符串
• Number：数字
• Boolean：布尔值
• Object：对象
• Array：数组

#变量传递流程

flowchart LR
  A[前序节点输出] --> B[变量选择器]
  B --> C[占位符替换]
  C --> D[当前节点输入]

系统会在运行时自动将占位符替换为实际的变量值。

#工作流执行

#执行模式

• 调试模式：逐步执行，查看每个节点的输入输出
• 正式运行：完整执行工作流
• 流式输出：支持流式返回 LLM 生成内容

#错误处理

• 节点执行失败时，工作流会中断并返回错误信息
• 可在节点配置中查看验证错误
• 调试模式下可查看详细的执行日志

#使用建议

#占位符支持总结

#外部调用

当您完成 AI Flow 的编排和测试后，可以通过 PIG AI SDK 在外部应用中调用已发布的工作流。

#基本调用示例

// 构建执行请求
FlowExecuteRequest request = FlowExecuteRequest.builder()
    .flowId(2003848423724408834L)           // 流程 ID
    .param("prompt", "你好，请介绍一下你自己")  // 输入参数
    .stream(true)                            // 流式返回
    .conversationId("session_001")           // 会话 ID
    .build();

// 流式执行，实时输出内容
client.executeFlowStream(request, event -> {
    System.out.print(event.getContent());
});

#了解更多

完整的 SDK 使用说明、Spring Boot 集成、异常处理等内容，请参考 PIG AI SDK 使用指南。